{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Weather MCP Server Demo\n",
        "\n",
        "This notebook demonstrates how to use the Weather MCP server to fetch weather data from Stormglass API.\n",
        "\n",
        "## Features\n",
        "\n",
        "- Get current weather conditions at any location\n",
        "- Get weather forecasts (up to 240 hours)\n",
        "- Get marine weather data (waves, swell, sea conditions)\n",
        "- Get comprehensive weather data (combining standard + marine)\n",
        "- Push notifications on successful weather queries\n",
        "\n",
        "**Note**: Requires `STORMGLASS_API_KEY` in your `.env` file.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Imports\n",
        "from dotenv import load_dotenv\n",
        "from agents import Agent, Runner, trace\n",
        "from agents.mcp import MCPServerStdio\n",
        "import os\n",
        "from IPython.display import Markdown, display\n",
        "\n",
        "load_dotenv(override=True)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Setup MCP Servers\n",
        "\n",
        "We'll use two MCP servers:\n",
        "1. **Weather Server** - For fetching weather data from Stormglass API\n",
        "2. **Push Server** - For sending notifications on successful queries\n",
        "\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import os\n",
        "from pathlib import Path\n",
        "\n",
        "current_dir = os.getcwd()\n",
        "print(f\"Current directory: {current_dir}\")\n",
        "\n",
        "# Check if STORMGLASS_API_KEY is set\n",
        "if not os.getenv(\"STORMGLASS_API_KEY\"):\n",
        "    print(\"⚠️ WARNING: STORMGLASS_API_KEY not found in environment variables.\")\n",
        "    print(\"Please set it in your .env file.\")\n",
        "else:\n",
        "    print(\"✓ STORMGLASS_API_KEY found\")\n",
        "\n",
        "# Check if Pushover credentials are set\n",
        "if not os.getenv(\"PUSHOVER_USER\") or not os.getenv(\"PUSHOVER_TOKEN\"):\n",
        "    print(\"⚠️ WARNING: PUSHOVER_USER or PUSHOVER_TOKEN not found in environment variables.\")\n",
        "    print(\"Push notifications will not work. Please set them in your .env file.\")\n",
        "else:\n",
        "    print(\"✓ Pushover credentials found\")\n",
        "\n",
        "weather_params = {\n",
        "    \"command\": \"uv\",\n",
        "    \"args\": [\"run\", \"weather_server.py\"]\n",
        "}\n",
        "\n",
        "push_params = {\"command\": \"uv\", \"args\": [\"run\", \"push_server.py\"]}\n",
        "\n",
        "print(\"✓ MCP server parameters configured\")\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Test the Weather MCP Server\n",
        "\n",
        "Let's first check what tools are available:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# List available tools from Weather MCP Server\n",
        "async with MCPServerStdio(params=weather_params, client_session_timeout_seconds=60) as server:\n",
        "    tools = await server.list_tools()\n",
        "    print(f\"Found {len(tools)} tools:\")\n",
        "    for tool in tools:\n",
        "        print(f\"  - {tool.name}: {tool.description[:100]}...\")\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Create a Weather Agent\n",
        "\n",
        "This agent can fetch weather data and send notifications when queries are complete.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "instructions = \"\"\"\n",
        "You are a weather assistant that helps users get weather information.\n",
        "You have access to comprehensive weather data from Stormglass API including:\n",
        "- Current weather conditions (temperature, humidity, wind, etc.)\n",
        "- Weather forecasts (up to 240 hours)\n",
        "- Marine weather data (waves, swell, sea conditions)\n",
        "- Comprehensive weather data (combining standard + marine)\n",
        "\n",
        "When users ask about weather:\n",
        "1. Use get_current_weather_tool for current conditions\n",
        "2. Use get_weather_forecast_tool for forecasts\n",
        "3. Use get_marine_weather_tool for coastal/marine locations\n",
        "4. Use get_comprehensive_weather_tool for complete weather picture\n",
        "\n",
        "IMPORTANT:\n",
        "- You can use EITHER location names (e.g., \"Nairobi, Kenya\") OR coordinates (latitude, longitude)\n",
        "- If user provides a location name, use it directly - the tool will automatically geocode it\n",
        "- If user provides coordinates, use them directly\n",
        "- If both are provided, coordinates take precedence\n",
        "- Present weather data in a clear, organized format\n",
        "- Include units (Celsius for temperature, m/s for wind speed, etc.)\n",
        "- After completing a successful weather query, you MUST call the 'push' tool to send a push notification\n",
        "  with a summary of the weather information retrieved (e.g., \"Weather for Nairobi: 14.4°C, 70% humidity, wind 1.55 m/s\")\n",
        "\n",
        "Be helpful and provide detailed weather information when requested.\n",
        "\"\"\"\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Example 1: Get Current Weather (Using Location Name)\n",
        "\n",
        "Get current weather conditions using just the location name - geocoding is automatic!\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "weather_query = \"Get the current weather conditions for Nairobi, Kenya\"\n",
        "\n",
        "async with MCPServerStdio(params=weather_params, client_session_timeout_seconds=60) as weather_server:\n",
        "    async with MCPServerStdio(params=push_params, client_session_timeout_seconds=60) as push_server:\n",
        "        agent = Agent(\n",
        "            name=\"weather_assistant\",\n",
        "            instructions=instructions,\n",
        "            model=\"gpt-4o-mini\",\n",
        "            mcp_servers=[weather_server, push_server]\n",
        "        )\n",
        "        \n",
        "        with trace(\"weather_current\"):\n",
        "            result = await Runner.run(agent, weather_query, max_turns=5)\n",
        "            \n",
        "        display(Markdown(result.final_output))\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Example 2: Get Weather Forecast (Using Location Name)\n",
        "\n",
        "Get a weather forecast using just the location name.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "forecast_query = \"Get a 48-hour weather forecast for Mombasa, Kenya\"\n",
        "\n",
        "async with MCPServerStdio(params=weather_params, client_session_timeout_seconds=60) as weather_server:\n",
        "    async with MCPServerStdio(params=push_params, client_session_timeout_seconds=60) as push_server:\n",
        "        agent = Agent(\n",
        "            name=\"weather_assistant\",\n",
        "            instructions=instructions,\n",
        "            model=\"gpt-4o-mini\",\n",
        "            mcp_servers=[weather_server, push_server]\n",
        "        )\n",
        "        \n",
        "        with trace(\"weather_forecast\"):\n",
        "            result = await Runner.run(agent, forecast_query, max_turns=5)\n",
        "            \n",
        "        display(Markdown(result.final_output))\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Example 3: Get Marine Weather (Using Location Name)\n",
        "\n",
        "Get marine weather data for a coastal location using just the location name.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "marine_query = \"Get marine weather data including wave height and swell conditions for Mombasa, Kenya for the next 24 hours\"\n",
        "\n",
        "async with MCPServerStdio(params=weather_params, client_session_timeout_seconds=60) as weather_server:\n",
        "    async with MCPServerStdio(params=push_params, client_session_timeout_seconds=60) as push_server:\n",
        "        agent = Agent(\n",
        "            name=\"weather_assistant\",\n",
        "            instructions=instructions,\n",
        "            model=\"gpt-4o-mini\",\n",
        "            mcp_servers=[weather_server, push_server]\n",
        "        )\n",
        "        \n",
        "        with trace(\"weather_marine\"):\n",
        "            result = await Runner.run(agent, marine_query, max_turns=5)\n",
        "            \n",
        "        display(Markdown(result.final_output))\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Example 4: Using Coordinates Directly\n",
        "\n",
        "You can still use coordinates directly if you prefer or have them available.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Example: Using coordinates directly (still works!)\n",
        "coords_query = \"Get current weather for latitude 1.2921, longitude 36.8219\"\n",
        "\n",
        "async with MCPServerStdio(params=weather_params, client_session_timeout_seconds=60) as weather_server:\n",
        "    async with MCPServerStdio(params=push_params, client_session_timeout_seconds=60) as push_server:\n",
        "        agent = Agent(\n",
        "            name=\"weather_assistant\",\n",
        "            instructions=instructions,\n",
        "            model=\"gpt-4o-mini\",\n",
        "            mcp_servers=[weather_server, push_server]\n",
        "        )\n",
        "        \n",
        "        with trace(\"weather_coordinates\"):\n",
        "            result = await Runner.run(agent, coords_query, max_turns=5)\n",
        "            \n",
        "        display(Markdown(result.final_output))\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Notes\n",
        "\n",
        "- **Geocoding is automatic!** You can use location names like \"Nairobi, Kenya\" or \"New York, USA\"\n",
        "- The tools will automatically convert location names to coordinates using Open-Meteo's free geocoding API\n",
        "- You can still use coordinates directly if you prefer\n",
        "- Make sure you have `STORMGLASS_API_KEY` set in your `.env` file\n",
        "- Make sure you have `PUSHOVER_USER` and `PUSHOVER_TOKEN` set for push notifications\n",
        "- Forecasts can be requested for up to 240 hours (10 days)\n",
        "- Marine weather data is particularly useful for coastal locations\n",
        "- Check your Pushover app for notifications about completed queries\n",
        "\n",
        "## Check Traces\n",
        "\n",
        "View detailed traces of the agent's weather queries:\n",
        "\n",
        "https://platform.openai.com/traces\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": ".venv",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.12.3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 2
}
